================================================================================
TEPS REGISTRATION CORE — DEPLOYMENT & OPERATIONS GUIDE
================================================================================

Contributors: Mikal Farley
Created:      April 2026
Last Updated: April 11, 2026


================================================================================
1. SYSTEM REQUIREMENTS
================================================================================

  Hardware:
    - Mac (Apple Silicon or Intel) running macOS 14 Sonoma or later
    - Wi-Fi or Ethernet network connection (for station devices)
    - No internet required for core functionality (offline-capable)

  Station devices:
    - Any device with a modern web browser (Safari, Chrome, Firefox)
    - iPads recommended for operator stations (host, camera, preview, POS)
    - Large screen or TV for overview dashboard and Santa display
    - All devices must be on the same local network as the Mac

  Network:
    - Port 8585 (default, configurable) must be accessible on the LAN
    - Bonjour/mDNS must not be blocked (used for auto-discovery)
    - Outbound HTTPS required only for: license checks, heartbeat,
      cloud sync, and credential validation


================================================================================
2. INSTALLATION
================================================================================

  1. Build and archive from Xcode, or install the signed .app bundle.
  2. Place TEPS Registration Core.app in /Applications.
  3. Launch the app. It will appear in the menu bar.

  App data locations:
    ~/Library/Application Support/TEPS Registration Core/
      registration.sqlite        — SQLite database
      ThemeAssets/                — uploaded background/logo images
      Exports/                   — CSV exports

    ~/Library/Application Support/TEPS Registration Core/Logs/ (via LogService)
      teps-reg-YYYY-MM-DD.log   — daily log files

  Sandboxing note:
    The app has an entitlements file (TEPS_Registration_Core.entitlements)
    for network server, outgoing connections, and file access. If sandboxed,
    the Desktop credential scan requires a security-scoped bookmark (granted
    via the Credentials settings panel).


================================================================================
3. FIRST-RUN SETUP
================================================================================

  Step 1: License Activation
  --------------------------
  On first launch, the License screen appears. Options:

    a) Enter a license code manually.
       The code is validated against ka.triprism.com.

    b) If another TEPS app is already licensed on this machine, the app
       checks the sentinel file at /var/tmp/.com.tpi.key.tpi and activates
       automatically.

    c) If the machine serial is already registered on the server, the app
       finds the key automatically (no code entry needed).

    d) Master override: Enter "1595" + today's two-digit day (e.g. "159511"
       on the 11th). This is a support-only bypass — not for production use.

  Step 2: Event Setup
  -------------------
  After license validation, the Setup wizard appears:

    LOCAL MODE:
      - Enter an event name (e.g. "Holiday Photos 2026")
      - The app creates a local event and starts the server
      - Best for: standalone setups, no internet needed

    SYNC MODE:
      - Enter: photographer name, location ID, event code, location name
      - The app creates a local event and enables cloud sync
      - Best for: multi-device setups with online reservations
      - Requires valid credentials (see Credential Setup below)

  Step 3: Verify Server
  ---------------------
  After setup, the success screen shows:
    - Server URL (e.g. http://192.168.1.100:8585)
    - QR codes for each station page
    - Station URLs ready to open on devices

  Open the dashboard window from the menu bar to verify counts.


================================================================================
4. CREDENTIAL SETUP (FOR PHOTO UPLOADS)
================================================================================

  Credentials connect the app to the photo upload service
  (upload.phototouchinc.com / secure.phototouchinc.com). They are NOT required for basic registration
  and queue management.

  Method 1: XML File Import (Recommended)
  ----------------------------------------
    1. Go to Settings > Credentials tab.
    2. Click "Grant Desktop Access" and select your Desktop folder.
    3. Place a credential XML file on your Desktop named like:
         credentials.xml
         credentials_XMAS_2026.xml
         credentials_HAUNTS.xml
    4. The app scans the Desktop every 30 seconds (or hourly if loaded).
    5. Credential sets appear in the Credentials tab.

    XML format:
      <credentials>
        <pt5_account>photographer_name</pt5_account>
        <pt5_location>ABCD-1234</pt5_location>
        <pt5_2_account>alt_name</pt5_2_account>
        <pt5_2_location>EFGH-5678</pt5_2_location>
      </credentials>

    Location IDs must be 8 alphanumeric characters (hyphens allowed but
    stripped for validation).

  Method 2: Manual Entry
  ----------------------
    Enter photographer and location ID directly in Settings > General.
    This is simpler but doesn't support multiple credential sets or seasons.

  Credential Validation:
    Click "Test" next to a credential set to verify it against the upload
    server. A test XML payload is sent; success means the account/location
    pair is recognized.

  Seasonal Scheduling:
    Multiple credential sets can be scheduled by date range in Settings >
    Seasons. Example:
      XMAS_2026: Nov 15 - Jan 5 (priority 1)
      HAUNTS:    Sep 15 - Nov 10 (priority 1)
    The highest-priority matching schedule for today's date is used.


================================================================================
5. STATION DEVICE SETUP
================================================================================

  For each station device (iPad, laptop, etc):

    1. Connect to the same Wi-Fi network as the Mac.
    2. Open the browser (Safari recommended on iPad).
    3. Navigate to the station URL shown in the app's Stations view.
       Example: http://192.168.1.100:8585/hoststation
    4. Bookmark the page or add to Home Screen for quick access.

  Station URLs:
    /hoststation       — Front desk check-in
    /elfstation        — Elf greeting station (optional)
    /camerastation     — Photographer queue + customer info
    /santa             — Santa/subject display (read-only)
    /previewstation    — Photo preview and selection
    /posstation        — Checkout / point of sale
    /overview          — Live queue dashboard (for TV/monitor)
    /registration      — Customer self-registration kiosk
    /tepsregistration  — Same as /registration (alternate URL)

  Tips:
    - Use "Add to Home Screen" on iPad for a full-screen experience
    - The overview page works great on a mounted TV
    - /registration can run on an unattended iPad as a self-serve kiosk
    - QR codes in the Stations view can be scanned by devices


================================================================================
6. CONFIGURATION CHECKLIST
================================================================================

  Before an event, review these settings:

  GENERAL TAB
    [ ] Server port (default 8585 — change if conflicts exist)
    [ ] Auto-start on launch (recommended: ON)
    [ ] Keep-alive (recommended: ON — auto-restarts on failure)

  REGISTRATION TAB
    [ ] Enable/disable form fields (email, phone, child name, etc)
    [ ] Set required fields
    [ ] Configure field order and custom labels
    [ ] Set up opt-in types (marketing consent, model release, etc)
    [ ] Configure walk-in profile if using wizard flow
    [ ] Set allow duplicates / allow multiple children

  PHOTO CODE TAB
    [ ] Choose code mode: auto, manual, reservation, reservation_manual
    [ ] Configure code segments if using auto mode
    [ ] Set upload type (PT5, PT5-2, PT5-3)

  WORKFLOW TAB
    [ ] Enable/disable elf station
    [ ] Enable/disable combined preview+POS
    [ ] Enable/disable combined host+camera (single-operator mode)
    [ ] Configure idle timeout
    [ ] Configure late marking grace period
    [ ] Set up local schedule if not using cloud sync

  CREDENTIALS TAB
    [ ] Grant Desktop access
    [ ] Verify credential sets are loaded and tested
    [ ] Set active upload type per credential set

  SEASONS TAB (if multi-season)
    [ ] Create date-range schedules for each credential set
    [ ] Verify correct set is active for today

  ADVANCED TAB
    [ ] Set passwords for Settings, Advanced, and License panels
    [ ] Review log retention period
    [ ] Export config as backup (can be imported on another machine)


================================================================================
7. DAILY OPERATIONS
================================================================================

  Start of Day:
    1. Launch the app (or verify it's running via menu bar icon).
    2. Green icon = server running. Orange = needs setup. Red = stopped.
    3. Open the dashboard to verify event name and zero counts.
    4. Test one station page in a browser to confirm connectivity.
    5. If using cloud sync, check sync status in the Status sidebar.

  During the Event:
    - Monitor the Dashboard for real-time registration and queue counts.
    - Use the Search panel to find specific customers.
    - The overview page (/overview) on a TV shows live queue depths.
    - If a customer needs a code change, use /changecode or the API.

  End of Day:
    1. Export registrations to CSV (Settings > Advanced > Export CSV).
    2. Review upload queues — flush any pending userdata/email/text uploads.
    3. The app can remain running between events.
    4. To start a new event, a new event must be created (POST /api/events
       or restart the app and go through setup again).

  Troubleshooting:
    - Station page won't load?
        Check the Mac's IP hasn't changed. Verify with the Stations view.
        Check that port 8585 is not blocked by firewall.
    - Server stopped unexpectedly?
        Keep-alive will auto-restart in 3 seconds. Check logs.
    - License expired?
        The app will show the license screen on next launch.
        Contact support for a new code.
    - Logs:
        Settings > Advanced shows the log directory. Click to open in Finder.
        Logs rotate daily: teps-reg-YYYY-MM-DD.log


================================================================================
8. CONFIG IMPORT/EXPORT
================================================================================

  Export:
    Settings > Advanced > Export CSV (for registration data)
    Programmatic: RegistrationConfig.exportConfig() returns a JSON dictionary
    containing all settings, field toggles, custom fields, themes, schedules,
    and password hashes. Data keys are base64-encoded for portability.

  Import:
    RegistrationConfig.importConfig(from:) restores a previously exported
    config dictionary. Returns the number of keys imported.

  Use case: Set up one Mac perfectly, export config, import on other Macs
  to clone the setup. Does not transfer event data or registrations.


================================================================================
9. SECURITY NOTES
================================================================================

  Network:
    - The HTTP server is unencrypted (HTTP, not HTTPS).
    - Intended for trusted local networks only.
    - Do not expose port 8585 to the public internet.

  Passwords:
    - Settings, Advanced, and License panels can be password-protected.
    - Passwords are SHA256-hashed and stored in UserDefaults.
    - Authentication is session-based (resets on app restart).
    - Master override: a daily-rotating support password, derived per-device from
      the machine serial + day-of-month via PBKDF2-HMAC-SHA256 keyed by an
      app-embedded secret (TEPSTX-287). It is NOT guessable from the serial alone.
      Support staff recompute it from the device serial; intentional for support
      access — do not share with end users.

  License:
    - License key is stored in UserDefaults and the sentinel file.
    - Sentinel file at /var/tmp/.com.tpi.key.tpi is world-readable.
    - License checks are done via HTTPS to ka.triprism.com.
    - Offline grace period: 24 hours from last successful check.

  Data:
    - All registration data is in a local SQLite file.
    - No encryption at rest. Physical access to the Mac = data access.
    - CSV exports land in Application Support — not automatically secured.
    - Cloud sync uses HTTPS but no end-to-end encryption.


================================================================================
10. EXTERNAL SERVICES
================================================================================

  Service                               Purpose
  ------------------------------------  ------------------------------------
  ka.triprism.com                       License activation and verification
  beta.admin.findyourpictures.com       Heartbeat, cloud sync, schedule pull
  upload.phototouchinc.com              Credential testing, code change uploads
  secure.phototouchinc.com              User data uploads (email, phone, etc)

  All external communication is optional. The app functions fully offline
  once licensed (within the 24-hour grace window) with local event mode.


================================================================================
11. KNOWN LIMITATIONS
================================================================================

  - Single active event at a time (last created event is active).
  - No HTTPS on the local server (use only on trusted networks).
  - No multi-user authentication on the API (any device on the network
    can make API calls).
  - Order totals are tracked but payment processing is external.
  - No automatic backup of the SQLite database.
  - Config import does not merge — it overwrites matching keys.


================================================================================
END OF DOCUMENT
================================================================================
